.\" man2html - UNIX Man Page to HTML translator
.TH man2html 8 "3 May 1996" "Michael Hamilton" "Linux"
.SH NAME
man2html \- UNIX Man Page to HTML translator
.SH SYNOPSIS
\fBman2html\fP [options] [pagespec]
.SH DESCRIPTION
\fBMan2html\fP is a UNIX Man Page to HTML translator that can be
used as a CGI interface for man page access via httpd daemons.
This man2html is actually called \fBVH-Man2html\fP which is
Richard Verhoeven's Man2html as modified and packaged up by Michael
Hamilton.
.B Man2html
can be used to view man pages using your web browser.
.B Man2html
can translate both man(7) and
.I mandoc
(BSD) macro styles.
It generates html directly from gnroff(1) and gtbl(1)
macro source without the need for
tbl/groff/nroff (sorry eqn isn't supported).
It generates links to other man pages and C include files.
Supporting CGI scripts allow you to browse HTML-ised whatis(1)
subject indexes and name-only indexes.
You can optionally add glimpse(1)
(a text indexing package) to do full text searches.
.PP
There are five ways of requesting pages:
.TP
.I "\fBman2html"
Invoking \fBman2html\fP without parameters causes the starting page
to be presented. You can use the search-able index on the starting
page to enter requests corresponding to following requests.
.PP
.TP
.I "\fBman2html \ \fIpage_name\fP"
Invoking \fBman2html\fP with a \fIpage_name\fP" as a parameter will
cause it to search for pages that match the name. If more than one
page is located, HTML for selecting any of the pages will be generated.
If a single page is located, its translation will be generated.
.PP
.TP
.I "\fBman2html \ \fIpage_name \ \fIsection_number\fP"
Similar to the above, but the required section is supplied to limit
the search.
.TP
.I "\fBman2html \-M \ \fIman_hierarchy_toplevel \ \fIpage_name \fP"
Similar to the above but the search is restricted to a particular
man page hierarchy, for example /usr/local.
.PP
.TP
.I "\fBman2html \ \fIfull_path_to\fIpage_name\fB.\fIsection_number \fP"
The specified man page is translated.
.SH BROWSING
To use these cgi scripts from a Web browser all you have to do is
point your web browser at
.nf
http://localhost/cgi-bin/man2html
.fi
You can either save this location as a bookmark or use an editor to
insert the following lines into an appropriate place in
a top level document.
.nf
.fi
The netscape-man(1) script allows you to enter man page requests at
the command line with the output presented in Netscape. If you are
already running netscape, the script will pass the request to the
existing browser. You can can use your shell to alias the name to
something shorter if you wish.
.B Man2html
has been tested with netscape(1) version 2.0 (I recommend Helvetica
fonts) and with lynx(1) (lynx can't do tables). Output for a large
number of pages has been verified with weblint(1).
.B Man2html
has also been tested as a server to other UNIX hosts.
.SH INSTALLATION
For some of the indexes to work you must generate the necessary
databases.
The manwhatis CGI script uses the /usr/man/whatis (see whatis(1)) file
to build a man page index. If this job has never been run (perhaps
because you turn your machine off at night when cron might be
scheduled to run it), you can build it by becoming the root user and
entering:
.nf
/usr/sbin/makewhatis /usr/man /usr/X11R6/man /usr/local/man
.fi
WARNING: makewhatis in Caldera 1.0 takes about 30 minutes on my
486DX66. I have a modified version of makewhatis so that it does
exactly the same job in only 1.5 minutes. My modified version is now
available as part of man-1.4g.tar.gz:
.nf
ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers
.fi
To use the Glimpse full text searching, you will need to install
glimpse in /usr/bin. Redhat rpm users can get glimpse from
.nf
ftp://ftp.redhat.com/pub/non-free/glimpse-3.0-1.i386.rpm
.fi
The glimpse home ftp site is cs.arizona.edu. N.B. glimpse is not
freely redistributable for commercial use. Having installed glimpse,
you will need to
build a glimpse index in /var/man2html. This doesn't take too long -
about 3 minutes on my 486DX2/66 16MB machine. As root do:
.nf
/usr/bin/glimpseindex -H /var/man2html /usr/man/man* /usr/X11R6/man/man* \
/usr/local/man/man* /opt/man/man*
chmod +r /var/man2html/.glimpse*
.fi
This could be set up as a cron job in /etc/crontab, e.g. (the following
must be all on one line):
.nf
21 04 * * 1 root /usr/bin/glimpseindex -H /var/man2html /usr/man/man*
/usr/X11R6/man/man* /usr/local/man/man* /opt/man/man* ;
chmod +r /var/man2html/.glimpse*
.fi
To serve man pages to remote hosts, all that is required is a httpd
daemon that sets the environment variable SERVER_NAME correctly.
The only problem you might have with this, is if your server machine
has dual-names.
.SH FILES
.TP
/home/httpd/html/man.html
Top level document loaded by man2html.
.TP
/home/httpd/html/mansearch.html
Search page.
.TP
/home/httpd/html/mansearchhelp.html
help for the search page.
.TP
/home/httpd/cgi-bin/man2html
The C program that translates man and mandoc macros to HTML.
.TP
/home/httpd/cgi-bin/manwhatis
Builds name-subject section indexes from the UNIX man whatis files.
.TP
/home/httpd/cgi-bin/mansearch
Does glimpse searches.
.TP
/home/httpd/cgi-bin/mansec
Searches the man page to create name-only indexes.
.TP
/usr/bin/netscape-man
Front end for netscape.
.TP
/var/man2html
This directory holds a cache of indexes computed by manwhatis and mansec.
They are updated if the whatis files or man directories are updated.
The glimpse index is also expected to live here.
.TP
\.\.\./man/whatis
Used by the manwhatis script.
.SH ENVIRONMENT
.TP
.B SERVER_NAME
is used to obtain the server-name for redirects when a partial
man-page specification is translated to a complete man-page path.
.SH SEE ALSO
.IR netscape-man (1) ,
.IR netscape (1) ,
.IR lynx (1)
.B http://www.actrix.gen.nz/users/michael/giveaways.html
.SH DISTRIBUTION
This program was written by Richard Verhoeven (NL:5482ZX35)
at the Eindhoven University of Technology. Email: rcb5@win.tue.nl
Permission is granted to distribute, modify and use this program as long
as this comment is not removed or changed.
My modifications, packaging and scripts are copyright (c) 1996
Michael Hamilton (michael@actrix.gen.nz). All rights reserved.
Permission is hereby granted, without written agreement and without
license or royalty fees, to use, copy, modify, and distribute this
software and its documentation for any purpose, provided that the
above copyright notice and the following two paragraphs appear in all
copies of this software.
IN NO EVENT SHALL MICHAEL HAMILTON BE LIABLE TO ANY PARTY FOR DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF MICHAEL
HAMILTON HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
MICHAEL HAMILTON SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
ON AN "AS IS" BASIS, AND MICHAEL HAMILTON HAS NO OBLIGATION TO
PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
.SH AUTHORS
VH-Man2html was was written by Richard Verhoeven (NL:5482ZX35) at
the Eindhoven University of Technology (Email: rcb5@win.tue.nl). The
original source is available from his web page at:
http://wsinwp01.win.tue.nl:1234/maninfo.html
BSD mandoc support, indexing scripts, Makefile, man pages, and other
packaging were added by Michael Hamilton (michael@actrix.gen.nz).
Maintenance and enhancement requests for this version should be directed
to Michael Hamilton (michael@actrix.gen.nz).